NOTE: This file is accompanied by an icon that contains "folding"
information used by TurboText. If you use TurboText as a text
reader, you will see this file collapsed, and you can expand the
sections you are interested in.
Asha's Silly Tagline Generator 1.8 Documentation
================================================
About ASTG
~~~~~~~~~~
ASTG is a tagline generator. For those people not familiar
with such things, a tagline generator's function is to create
random quotes that appear at the end of a message, maybe
humorous, maybe not. Taglines are more or less bumper stickers
for electronic mail.
ASTG 1.0 (and later revisions) was created specifically for
Asha Develder as a birthday present. While I could spend a
few pages describing Asha and why she has inspired me to write
a program just for her, I think she speaks best for herself,
so catch her in the Fidonet echos, AMIGA (sometimes called
Amiga General) and the echo she moderates, AMIGAGAMES. To
know her is to love her. :-)
Anyway, Happy Birthday, Asha!!!
ASTG was designed to work with most popular offline readers
and point programs, such as Spot, April, or Foozle. It may
well work with other programs but I have not had the
opportunity to try them with it. If you get ASTG to work with
one of these other programs, please contact me and let me know
how you did it, and I'll include that information in any
future releases (if any) of the program's docs.
History of ASTG
===============
ASTG began its life as an Arexx script that was released as
ASTG07.LHA (sysops, if you have this one, you may delete it).
While it worked fine for me, it was a bit slow on the larger
tagline files. Asha especially disliked having to wait for
Arexx to makes its way through the large collection of
taglines she had, hence my motivation to speed things up for
her.
ASTG the Rexx script was developed partly from QUOTEMONGER,
another Arexx tagline generator. Well, two or three lines of
the original code remained after I hacked it :-)
ASTG 0.7 seems to have developed a reputation for being
psychic. I make NO claims of ownership for this -- the source
code for 0.7 is available and I can find nothing in it
representing an AI function, and no one has pointed that block
of code out to me, either. It SEEMS that that certain
*something* has carried over to the C version, too. One thing
we have noticed is that it takes a while for ASTG to get
"used" to you before things start happening.
FEATURES
========
ASTG offers several features that might not be individually
unique, but as a whole it offers a comprehensive package:
o Marks taglines as they are used. This ensures that you
cycle through ALL your taglines before it starts over,
which means basically that you get to see them all over
the course of time. Typical C and Arexx randomizing
functions -- aren't, so they don't normally provide much
variety in taglines.
o Allows taglines of over one line in length. The taglines
have to be formatted in a specific way for this to work
(read on).
o Intuition based Prefs editor. Easy to set up!
o Works with most text editors
o Works with any message system that calls an external editor
and stores the message in an external text file.
o FAST! Written in C for speed!
Requirements
============
ASTG 1.7 requires AmigaDOS 2.04 or later. ReqTools.library
version 38 or later is required for the prefs program. It also
requires a message writing system of some sort and a file of
taglines (sample tagline file included, but PLEASE start
your own personalized collection! Otherwise, the magic will not
work!).
Installation
============
If you have been using ASTG 1.0 through 1.4, you will have to
delete ENV:ASTG.PREFS and re-run ASTG Prefs! Sorry about that,
but there was a problem in the way I was reading the prefs file,
and the easiest way to correct it was to completely change the
way I did things.
ASTG Archive
~~~~~~~~~~~~
From the ASTG archive, copy the following files:
ASTG Prefs Copy this file and its icon to your
ASTG Prefs.info SYS:Prefs directory. Actually, it can go
anywhere, but the PREFS dir is the
logical place to put it.
ASTG Copy this program to where you plan to
use it -- C: is fine, as is where you
keep your mail reader. As long as you
can find it later...
Taglines This is a sample tagline file. Put it
wherever you like, but be sure to
remember where it went, as you'll
probably wish to edit it later on. You
can also rename it to anything you wish.
ASTG.DOC Put this file anywhere you wish :-)
Your Mail Program
~~~~~~~~~~~~~~~~~
SPOT
~~~~
In the SETTINGS menu, select GENERAL. On the setup
window you get, set EDITOR to:
<path>/ASTG %s
where <path> is the drive and path that ASTG is stored
in.
APRIL
~~~~~
In the CONFIGS menu, select GENERAL1. On the setup
window you get, set EDITOR to:
<path>/ASTG
where <path> is the drive and path that ASTG is stored
in.
FOOZLE
~~~~~~
Run FZI. Click on GENERAL1. Cycle through until you
find the "Editor" window. Set it to
<path>/ASTG %
where <path> is the drive and path that ASTG is stored
in.
Configuring ASTG Prefs
======================
Double click on the ASTG Prefs icon. A window will pop up
with four parameters that you can set:
Tag File This is the path and filename of the tagline
file. Click on the button next to it to get
a file requester.
Editor 1 This is the path and filename of the editor
you use to write messages, and the first
part of any parameters you need to pass it,
up to but not including the filename that
you will be editing. Click on the button
next to it to get a file requester.
For example, if you're using TurboText, you
might set it to TurboText:TTX. The next
thing you would NORMALLY put in that line
would be the file name itself. ASTG gets
that from the mail program itself, so don't
put it in here.
Editor 2 Some editors require parameters AFTER the
file name. This is where you would put it.
If there is nothing you need to put there,
make it blank.
For example, Turbotext will let the parent
process go immediately after it is called,
normally, but you can make it wait until you
finish editing the message with the WAIT
parameter. Another example would be the
CygnusEd -keepio parameter.
Brag Line ASTG normally lets the world know that
you're using it. If this checkbox is turned
off, it won't. It won't bruise my ego if
you want to be incognito :-) If I was
worried about it, I wouldn't have made it an
OPTION. :-) Also, for the bandwidth-concious,
you'll probably want to turn this off in order
to save precious bytes in your outgoing mail
packets (no comment :-)
Creating and editing the tagline file
=====================================
NOTE: if you have been using ASTG 0.7, you DO NOT need to
change your tagline file except to delete the "###" at the
end.
IMPORTANT >>>>>>>>>
The tagline file can contain as many taglines as you wish.
The ONLY constraint is how much memory you have -- be
warned that ASTG loads the ENTIRE tagline into memory, so
if you have a 500K tagline file wow!) you need to have at
least 500K of memory free to use it.
END IMPORTANT >>>>>
Each line in the tagline file represents one single
tagline.
Each tagline, as I mentioned, can be a multi-line tagline.
To do this, seperate each 'line' in the tagline with the
two characters, "\n". You will notice several taglines in
the sample file are formatted like this.
For example:
... Tell a man that there are 300 billion stars in the galaxy and\n he'll believe you. Tell him a bench has wet paint and he'll have\n to touch it to be sure. -- M.B.
(if your text reader doesn't let you see it properly, the
above should have been seen all on one line).
translates to:
... Tell a man that there are 300 billion stars in the galaxy and
he'll believe you. Tell him a bench has wet paint and he'll have
to touch it to be sure. -- M.B.
NOTE:
EXCESSIVE USE OF THIS FUNCTION MAY RESULT IN YOUR
BEING FLAMED BY OTHER PEOPLE ON THE NET FOR WASTING
BANDWIDTH. IF THIS HAPPENS, IT'S YOUR FAULT. I SUPPLY
THE PROGRAM, WHAT YOU DO WITH IT ISN'T MY FAULT.
General information: (for the technically minded)
====================
So far, I've presented several specific examples. Now, I'll
go more into depth with this so that people with different
programs can possibly make it work. If you do, please let
me know and I'll include your information in any future
releases.
ASTG Command Line
~~~~~~~~~~~~~~~~~
Usage: ASTG <Message File>
ASTG takes most of its parameters from ENV:ASTG.PREFS.
One filename, the name of the message file itself, must
be supplied by the mail program. This file must be a
plain text file.
ASTG Operation
~~~~~~~~~~~~~~
ASTG does several things as it goes along. First, it
opens the tagline file that it is directed to in the
prefs file, counts up the number of unused taglines, and
randomly selects one to use. It marks that tagline with
a "*" as the first character, then re-writes to the
tagline file with the changed information.
It then parses and appends that tagline to the end of
the message. If it is directed to, it appends a
bragline.
Finally, it calls the prefs-selected text editor, using
the name of the message file supplied on the command
line by the calling message reader.
In your mail program, there is probably a place that you
tell it what editor to use. If there is not, you
probably cannot use ASTG with it. In that program, you
substitute ASTG for the editor. Be sure to follow that
program's conventions for supplying the message file
name.
If there are less than 3 free taglines, ASTG will remove
the markers before writing the taglines back to the
file. This takes a bit of time, but it only happens
occasionally.
ASTG.Prefs
~~~~~~~~~~
ASTG uses the style guide suggested method of storing its
configuration data in ENV: and ENVARC: as ASTG.PREFS.
You should not change this manually.
TECHNICAL SUPPORT, AND REGISTRATION
===================================
I'll get the easy part out of the way, first. This program is
freeware. Use it in good health. Fercrissakes, this is just
a stupid tagline generator! Take that registration money and
spend it on something worthwhile, like your sweetheart!
OK, the odds of this program being bug-free are pretty slim.
As such, I very much want to hear of any bugs you come across.
If you do, please let me know about the version of the OS you
use, the CPU and memory in your computer, and whether you're
using a hard drive for this. Also, open a shell, and CD to
the directory that ASTG lives in. Type "VERSION ASTG FULL"
and record the information you get and pass that along. Be
prepared to somehow get your tagline file to me, too, as it
may be something in your tagline file that's doing it (but
don't send it unless I ask for it!). Finally, ASTG will
report an error code when it fails. Please let me know what
code that is, as it will point me to the exact location in the
code of the failure. If you're up to it, try to reproduce the
failure and see if it fails in the same place.
You can contact me on FidoNet as:
Jeff Grimmett at 1:202/720 (not crashable)
... or on Internet as:
jgrimm@sdd.hp.com
... or on GENie as:
J.Grimmett2
You can contact me via SnailMail as:
Jeff Grimmett
3152 Kemper St #5
San Diego, CA
92110
Future Plans
============
The few items I have left:
o Implement keyboard support for the prefs program (not that
there's much to implement...)
o Remove final dependencies on ReqTools.library in the prefs
program.
Not much left to do!
ACKS!
=====
I'd like to thank my beta testers, Holly Sullivan, Joyce
Divina, and Gary Peake. Oh, and Asha Develder, as well :-)
ASTG Prefs was built using GadToolsBox, sadly no longer
supported by the author. :-(
ASTG and ASTG Prefs were built using SAS/C 6.3, a wonderful
development system on any platform!
Thanks to Oxxi for TurboText, which was used for both the code
editing and for document generation :-)
Thanks to the various offline reader and point software
authors for making thier products useable even unregistered.
If it weren't for that, if would be darned difficult to test
ASTG under varying conditions.
History File
============
Version 1.8 (15 April 1995) (Happy Easter, Asha!)
o Removed the backup code in ASTG. It was creating more
problems than it was worth. Users would run ASTG after ASTG
bombed out, and the empty file would be backed up, destroying
the good file. Since no one (including myself) was benefiting
from the backup option, I took it out to save space.
o ASTG got rewritten from the ground up. This was due to the
fact that although ASTG was running flawelessly on countless
systems, it was still crashing on Asha's machine. This is not
good, since it is Asha's program! ALL SAS/C str* string
functions were removed or my own code was substituted. ASTG
is slightly slower, but now seems to be running stable on
Asha's machine. As a side effect, the code is around 2K
smaller.
Version 1.7 ( 2 April 1995) *BETA*
ASTG would crash horribly if the tagline file was 0 bytes
long. Code has been added to exit gracefully if that happens.
If you see this error, it is probably because ASTG bombed out
in an earlier run.
Implemented the PARANOID MODE of programming ASTG. This means
that ASTG error checks practically everything it does and
fails if anything is remiss, but it prints an error code when
it does so. This should facilitate troubleshooting of bugs
that I cannot reproduce here.
As part of the PARANOID philosophy, I have implemented a
backup mode in ASTG. Before it touches your tagline file, it
copies the file to the same directory with the ".bk" suffix.
Removed, for philosophical reasons, all dependencies in ASTG
itself on ReqTools. The dependencies still exist in ASTG
Prefs. One thing at a time, ambassador, one thing at a time.
Version 1.6 (19 March 1995)
Rewrote the Prefs File editor and the prefs file portion of
ASTG. You MUST delete the old ENV:ASTG.Prefs and rerun the
prefs program. Sorry!
Version 1.5
A radical departure from 1.3 and 1.4, it was actually found to
be SLOWER than the older ones. As such, it was scrapped.
Version 1.4 (13 March 1995)
Changed "cleanup" function to utilize a faster method of
writing out the tagline file when it's cleaning out the
"*"'s. I don't think there's anything else that can be
done to increase the speed of ASTG now.
Removed all references to ANY "printf" related functions
(fprintf, sprintf), which reduced the code size by 4K or
thereabouts.
Yet another speed increase -- this time, on the file
write-back. Changed it from line I/O to buffered I/O.
Unfortunately, it does not appear that this is possible for
the "clean-up" operation.
Found and stomped one more bug, this one introduced in 1.3.
The memory buffer used to store the tagline selected was
exactly one byte too large. Thus, a garbage character was
being tacked on to the end of each tagline in the tagline
file.
Version 1.3 (14 Feb 1995) (Happy Valentine's day, Asha!)
Nailed it! Well, I think so...
For the technically oriented, strtok() is a little brain
dead and tends to overflow if you tell it to parse a string
for "\n" and it doesn't find it. I fixed this by
calloc()-ing a chunk of memory one byte larger than the
tagline file, and strset()-ing it to "\n", thus
guaranteeing that there is a CR at the end of the last line
parsed.
Side effect: the first time you use it, ASTG causes the
tagline file to grow by one byte. At this time, I am not
certain if this will cause any ill effects, but time will
tell.
There is no indication as to the cause of the failure of
ASTG to parse the bragline setting. I am assuming at this
time that it was a side-effect of the memory grunging
happening due to the tagline corruption problem. Only time
will tell.
Version 1.2 ( 9 Feb 1995)
Internal release.
There are two known bugs in ASTG. One causes it to not
properly parse the bragline on/off switch. The other is
more major, and causes it to occasionally corrupt the
tagline file. In many cases, ASTG hangs up because of it.
Major changes made to speed the execution of the program.
This has caused the bug that corrupts the tagline file to
stand up and be really noticable, which makes it easier to
troubleshoot. It goes without saying that ASTG will not be
released in this condition.
One side effect of the change is that the "###" is no
longer needed at the end of the tagline file. In fact, if
it is left in, it will eventually be seen as a tagline! :-)
Another side effect is that the number of taglines you have
is now limited only by how much memory you have.
Version 1.1 ( 3 Jan 1995)
Several changes made to increase the execution speed. I am
still not altogether satisfied with the speed, but it now
takes 1/5 the time it took version 1.0 to execute on the
same sized tagline file, so that's some progress! :-) All
speed changes were accomplished by inlining several
functions within the program.
Added an extra <CR> before the tagline, at Asha's request.
Hey, it's HER birthday present! :-)
Trimmed out a lot of excessive junk (debugging code, catch
code, stdio code, etc) to reduce the size of the program by
